home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / g_man / cat3 / standard / readdisplay.z / readdisplay
Encoding:
Text File  |  2002-10-03  |  8.1 KB  |  199 lines
  1.  
  2.  
  3.  
  4. rrrreeeeaaaaddddddddiiiissssppppllllaaaayyyy((((3333GGGG))))                                                rrrreeeeaaaaddddddddiiiissssppppllllaaaayyyy((((3333GGGG))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      rrrreeeeaaaaddddddddiiiissssppppllllaaaayyyy - reads a rectangular screen region, returning displayed
  10.      pixel colors in a packed RGB format.
  11.  
  12. CCCC SSSSPPPPEEEECCCCIIIIFFFFIIIICCCCAAAATTTTIIIIOOOONNNN
  13.      lllloooonnnngggg rrrreeeeaaaaddddddddiiiissssppppllllaaaayyyy((((SSSSccccrrrreeeeeeeennnnccccoooooooorrrrdddd xxxx1111,,,, SSSSccccrrrreeeeeeeennnnccccoooooooorrrrdddd yyyy1111,,,,
  14.                       SSSSccccrrrreeeeeeeennnnccccoooooooorrrrdddd xxxx2222,,,, SSSSccccrrrreeeeeeeennnnccccoooooooorrrrdddd yyyy2222,,,,
  15.                       uuuunnnnssssiiiiggggnnnneeeedddd lllloooonnnngggg ****ppppaaaarrrrrrrraaaayyyy,,,, uuuunnnnssssiiiiggggnnnneeeedddd lllloooonnnngggg ****hhhhiiiinnnnttttssss))))
  16.  
  17. PPPPAAAARRRRAAAAMMMMEEEETTTTEEEERRRRSSSS
  18.      _x_1     expects the x screen coordinate of one corner of the rectangle.
  19.  
  20.      _y_1     expects the y screen coordinate of one corner of the rectangle.
  21.  
  22.      _x_2     expects the x screen coordinate of the opposite corner of the
  23.             rectangle.
  24.  
  25.      _y_2     expects the y screen coordinate of the opposite corner of the
  26.             rectangle.
  27.  
  28.             These coordinates are relative to the lower-left pixel on the
  29.             screen, whose coordinates are 0,0.  It does not matter whether x1
  30.             is greater than or less than x2, nor y1 greater than or less than
  31.             y2.
  32.  
  33.             The rectangle specification is inclusive.  Thus the rectangle
  34.             specified by coordinates 5,10,14,6 is 10 pixels wide and 5 pixels
  35.             high.
  36.  
  37.      _p_a_r_r_a_y expects the array that is to receive the pixels that are read.
  38.             Pixels are returned in packed ABGR format, with red occupying the
  39.             lower 8 bits and alpha (if available) occupying the upper 8 bits.
  40.             Returned alpha is one (0xff) if the pixel is in color index mode
  41.             or if no alpha bitplanes are present.  Return order is left-to-
  42.             right, then bottom-to-top, i.e.
  43.  
  44.  
  45.  
  46.                      6  7  8
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. rrrreeeeaaaaddddddddiiiissssppppllllaaaayyyy((((3333GGGG))))                                                rrrreeeeaaaaddddddddiiiissssppppllllaaaayyyy((((3333GGGG))))
  71.  
  72.  
  73.  
  74.                      3  4  5
  75.  
  76.  
  77.  
  78.                                0  1  2
  79.  
  80.  
  81.                _h_i_n_t_s
  82.                     hints is an unsigned long passed to rrrreeeeaaaaddddddddiiiissssppppllllaaaayyyy which
  83.                     serves as a bit mask for enabling the various rrrreeeeaaaaddddddddiiiissssppppllllaaaayyyy
  84.                     modifiers delineated in the list of constants below.  The
  85.                     constants are specified by bitwise ORing them, or by
  86.                     adding them.  For example,
  87.  
  88.                     readdisplay(0,0,99,99,parray,(RD_FREEZE+RD_ALPHAONE));
  89.  
  90.                     blocks graphics while reading the display and returns an
  91.                     image in which alpha is equal to one.
  92.  
  93.                     These modifiers are hints, not directives, and are
  94.                     therefore ignored by systems that do not support the
  95.                     requested feature.
  96.  
  97.                     The following hints are available:
  98.  
  99.                     RRRRDDDD____FFFFRRRREEEEEEEEZZZZEEEE freezes the screen by blocking all graphics
  100.                     calls until the read is completed.  This assures that the
  101.                     returned data accurately represents what was being
  102.                     displayed at the time of the call.
  103.  
  104.                     If graphics calls are allowed to proceed while rrrreeeeaaaaddddddddiiiissssppppllllaaaayyyy
  105.                     is executing, it is possible that the returned data may
  106.                     not resemble what was displayed at the time of execution,
  107.                     since drawing commands and commands that affect the
  108.                     display state ( etc.) can change the displayed data while
  109.                     it is being read.
  110.  
  111.                     RRRRDDDD____AAAALLLLPPPPHHHHAAAAOOOONNNNEEEE returns all alpha values set to one
  112.                     (represented as 0xff in the color space of this command).
  113.  
  114.                     If not requested, actual alpha values are returned if
  115.                     alpha planes are installed and the pixel is in RGB mode.
  116.                     One (0xff) is returned for pixels in color index mode or
  117.                     if no alpha planes are installed.
  118.  
  119.                     RRRRDDDD____IIIIGGGGNNNNOOOORRRREEEE____PPPPUUUUPPPP ignores the contents of the pop-up
  120.                     framebuffer.
  121.  
  122.                     RRRRDDDD____IIIIGGGGNNNNOOOORRRREEEE____OOOOVVVVEEEERRRRLLLLAAAAYYYY ignores the contents of the overlay
  123.                     framebuffer.
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. rrrreeeeaaaaddddddddiiiissssppppllllaaaayyyy((((3333GGGG))))                                                rrrreeeeaaaaddddddddiiiissssppppllllaaaayyyy((((3333GGGG))))
  137.  
  138.  
  139.  
  140.                     RRRRDDDD____IIIIGGGGNNNNOOOORRRREEEE____UUUUNNNNDDDDEEEERRRRLLLLAAAAYYYY ignores the contents of the underlay
  141.                     framebuffer.
  142.  
  143.                     RRRRDDDD____OOOOFFFFFFFFSSSSCCCCRRRREEEEEEEENNNN Data read beyond the framebuffer boundary is
  144.                     returned equal to zero, regardless of the setting of this
  145.                     hint.  Reading beyond the framebuffer boundary may reduce
  146.                     performance.
  147.  
  148. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  149.      rrrreeeeaaaaddddddddiiiissssppppllllaaaayyyy generates the displayed value of each addressed pixel, taking
  150.      into account all display bitplanes and modes except those of the cursor.
  151.      The ABGR values returned therefore correspond to the values viewed on the
  152.      monitor, with the following exceptions:
  153.  
  154.           1. The returned values are not gamma corrected.
  155.  
  156.           2. The cursor will not appear in the returned data.
  157.  
  158.           3. If either of the hints RD_IGNORE_UNDERLAY, RD_IGNORE_OVERLAY, or
  159.           RD_IGNORE_PUP is set, the corresponding framebuffer data will not be
  160.           included in the returned data.
  161.  
  162. FFFFUUUUNNNNCCCCTTTTIIIIOOOONNNN RRRREEEETTTTUUUURRRRNNNN VVVVAAAALLLLUUUUEEEE
  163.      rrrreeeeaaaaddddddddiiiissssppppllllaaaayyyy returns the number of pixels read.
  164.  
  165. NNNNOOOOTTTTEEEESSSS
  166.      This subroutine is available only in immediate mode.
  167.  
  168. BBBBUUUUGGGGSSSS
  169.      On IRIS-4D VGX and VGXT models, rrrreeeeaaaaddddddddiiiissssppppllllaaaayyyy does not correctly read the
  170.      underlay planes when the program is double buffered.
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.